package com.google.gwt.gwtpages.client.page.loader;

import com.google.gwt.gwtpages.client.GWTPagesSettings;
import com.google.gwt.gwtpages.client.message.exceptions.PageNotFoundException;
import com.google.gwt.gwtpages.client.page.GWTPage;
import com.google.gwt.gwtpages.client.page.GWTPageAttributes;
import com.google.gwt.gwtpages.client.page.parameters.GWTPagesTokenizer;
import com.google.gwt.gwtpages.client.page.parameters.PageParameters;


/**
 * Interface class used to load pages based on their "token". The token
 * represents the full history token or partial history token (if accompanied by
 * additional parameters). The page token is identified by the
 * {@link GWTPagesTokenizer}. The page loaded returns pages using a callback
 * mechanism so they can optionally be implemented in an async fashion.
 * 
 * @author Joe Hudson
 */
public interface GWTPagesLoader {

	public static final String PAGE_DEFAULT = "";

	/**
	 * Initialize the loader. This is where all pages would be registered.
	 */
	public void init(GWTPagesSettings settings);

	/**
	 * Return true if the page token is mapped to a known page and false if not
	 * 
	 * @param pageToken
	 *            the page token
	 */
	public boolean isValidPageToken(String pageToken);

	/**
	 * Return the optional {@link GWTPageAttributes} associated with this page token
	 * 
	 * @param pageToken
	 *            the page token
	 * @return the {@link GWTPageAttributes} or null
	 * @throws PageNotFoundException
	 *             if no page was mapped to the provided page token
	 */
	public GWTPageAttributes getMetaData(String pageToken)
			throws PageNotFoundException;

	/**
	 * Method to execute when requesting a page. One of the
	 * {@link PageLoadCallback} handler methods *must* be called depending on
	 * the state of the page request.
	 * 
	 * @param pageToken
	 *            the page token
	 * @param pageHandler
	 *            the {@link PageLoadCallback}
	 */
	public void getPage(String pageToken, PageLoadCallback pageHandler);

	/**
	 * Return true if the requested page should be kept in the page stack after
	 * a new page is requested and false otherwise.
	 * 
	 * @param pageData
	 *            the {@link GWTPage}
	 * @param parameters
	 *            the page parameters
	 */
	public boolean keepInStack(GWTPage pageData,
			PageParameters parameters);
}